Once a plugin is complete, we may want to publish it
so that others can benefit from—and possibly
improve—the code. We can do this at the official jQuery Plugin Repository at http://plugins.jquery.com/. Here we can log in, or register if we need to, and follow the instructions to describe the plugin and upload a .zip
archive of its code. Before this, though, we should make sure the
plugin is appropriately polished and prepared for public consumption.
There are a few rules to
follow in writing plugins in order to play well with other code. We
have covered some of these in passing already, but they are collected
again here for convenience.
Naming conventions
All plugin files should be named jQuery.myPlugin.js where myPlugin is the name of the plugin. Within the file, all global functions should be grouped into an object called jQuery.myPlugin, unless there is only one, in which case it may be a function just called jQuery.myPlugin().
Method names are more flexible, but should be kept as unique as possible. If only one method is defined, it should be called jQuery.fn.myPlugin().
If more than one is defined, attempt to prefix each method name with
the plugin name to prevent confusion. Avoid short, ambiguous method
names such as .load() or .get() that may be confused with methods defined in other plugins.
Use of the $ alias
jQuery plugins may not assume that the $ alias is available. Instead, the full jQuery name must be written out each time.
In longer plugins, many developers find that the lack of the $
shortcut makes code more difficult to read. To combat this, the
shortcut can be locally defined for the scope of the plugin by defining
and executing a function. The syntax for defining and executing a
function at once looks like this:
(function($) {
// Code goes here
})(jQuery);
The wrapping function takes a single parameter, to which we pass the global jQuery object. The parameter is named $, so within the function we can use the $ alias with no conflicts.
Method interfaces
All jQuery methods get called within the context of a jQuery object, so this
refers to an object that may refer to one or more DOM elements. All
methods must behave correctly regardless of the number of elements
actually matched. In general, methods should call this.each() to iterate over the matched elements, operating on each one in turn.
Methods should return
the jQuery object to preserve chaining. If the set of matched objects
is modified, a new object should be created by calling .pushStack()
and this object should be returned instead. If something other than a
jQuery object is returned, this must be prominently documented.
If methods take several
options, it is preferable to use a map as an argument so that the
options are labeled and can be specified in any order. Default values
should be defined in a map that can be overridden if necessary.
Method definitions must end in
a semicolon (;) character so that code compressors can properly parse
the files. In addition, plugins may begin with a semicolon, so that
other poorly-coded scripts do not cause conflicts after compression.
Documentation style
In-file documentation
should be prepended to each function or method definition in ScriptDoc
format. This format is documented at http://www.scriptdoc.org/.